You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
bun-types: declare the absent values of spawnSync().exitCode and of the socket address and TLS getters - #48411
Eleven declarations leave out the value the runtime returns when there is none. Bun.spawnSync().exitCode is null after a signal kills the child, but bun.d.ts:8700 says number, so exitCode > 1 is silently false.
The address properties of Bun.Socket (bun.d.ts:7264-7294), ServerWebSocket.remoteAddress (serve.d.ts:273) and three TLS getters have the same gap. ws.remoteAddress.toUpperCase() in close passes tsc and throws TypeError: undefined is not an object.
Declare exitCode: number | null, | undefined for the seven address properties, getServername() and getPeerX509Certificate(), and getTLSVersion(): string | null. The JSDoc says when each value is absent.
Correct because no runtime value changes, and node:child_process and node:net already read these values.
Verified: test/integration/bun-types/bun-types.test.ts. The new fixture lines give 12 diagnostics on main.
Self-reviewed: 7 concerns raised, 6 addressed. Not done: a tracking issue for the members left out. The Notes list them.
Background
The address getters ask the operating system. A Unix domain socket has no IP address, and a closed socket has no descriptor to ask.
Users of @types/bun get a strictNullChecks error where they read these values without a check: 8 places in test/ here. Three took a signal death for a number.
Other members of Bun.Socket and Bun.udpSocket keep the same gap.
No cost at run time. The compressed declarations in the binary grow by 4 bytes.
Notes
Runtime values, on 1.4.4-canary.1+2596ac5d3 (Linux x64) and on 1.4.3
Read
Value
Bun.spawnSync(...).exitCode after SIGKILL, and after timeout or maxBuffer when the signal ends the child
null
All six address properties of a socket of Bun.listen({ unix }) or Bun.connect({ unix })
undefined
The same six on a TCP socket, first read in close, after close, or in connectError
undefined
remoteFamily, remoteAddress, remotePort in open, when the peer wrote and reset before the accept
undefined
remotePort on a TCP socket after close, also when it was read in open
undefined
ws.remoteAddress over Bun.serve({ unix }), and on a TCP server when the first read is in close
undefined
getTLSVersion() on a socket without TLS, and after a TLS socket closes
null
getServername() on a socket without TLS, after close, and when the client sent no server name
undefined
getPeerX509Certificate() on a TLS server socket whose client sent no certificate, and after close
undefined
A child that handles the signal of timeout can still exit with a code: sh -c "trap 'exit 0' TERM; sleep 5 & wait" with timeout: 200 gives exitCode: 0 and exitedDueToTimeout: true. So the JSDoc of exitCode names the signal, not the option, as the cause.
Why the declaration is the side that changes
exitCode: src/runtime/api/bun/subprocess.rs:1310 returns null unless the child exited. spawnsync-no-microtask-drain.test.ts:87 and spawn-kill-signal.test.ts pin null. src/js/node/child_process.ts:588 maps it to Node's status: null. The table of built-ins already says exitCode: b.f64.nullable (src/codegen/builtins/host/globals.builtins.ts:1129).
Socket addresses: the schema already says string | undefined and u16.optional (src/runtime/socket/socket_body.bind.ts:10, :69-78). src/js/node/net.ts:3137-3165 depends on undefined for a Unix domain socket, as Node does. socket.test.ts:5135 pins undefined.
ServerWebSocket.remoteAddress: src/runtime/server/server.bind.ts:159 says string | undefined. websocket-server.test.ts:3768 pins that a value read in open is still there in close. The schema check in bun-types.test.ts listed this row as a known difference. The row is gone.
@types/node declares the Node equivalents the same way: SpawnSyncReturns.status: number | null, remoteAddress: string | undefined, localAddress?: string.
Members with the same gap that this PR does not change
Checked on the same canary build.
Member
Declared
Runtime
Socket#getPeerCertificate()
PeerCertificate
null without TLS. undefined on a TLS server whose client sent no certificate, and after close
Socket#getCertificate()
PeerCertificate | object | null
undefined without TLS, on a TLS client without a certificate, and after close
On a connected TLS socket most of the TLS getters always have a value, so a wider type makes every caller add a check. exportKeyingMaterial() needs its two declarations merged first. The UDP values are absent only after the program itself called close().
src/js/private.d.ts:449 repeats readonly remoteAddress: string for the built-in modules, and src/js/node/child_process.ts:588 still retypes exitCode, stdout and stderr. Both are internal annotations and still type-check. This PR has no file under src/.
The schema check
The check ("promises nothing that a schema of the bindgen breaks") compares only classes that an export with a constructor leads to. socket_body.bind.ts maps to null, so it never compared TCPSocket and TLSSocket with Bun.Socket.
An extension that compares them is on the branch robobun/e8bf2afd/schema-check-instance-classes (03be80c). It changes compare(), which bindgen: delete b.any and .variadic #46789 also changes, and its expected rows print type names of @types/node, which the fixture installs at latest. It is not in this PR.
bun test test/integration/bun-types/bun-types.test.ts: 30 pass. With the two .d.ts files of main: the fixture case fails with 12 TS2344 diagnostics (spawn.ts:192-193, tcp.ts:177-185, websocket.ts:357) and the schema check prints the ServerWebSocket row.
tsc --noEmit in test/: the declarations give 8 new diagnostics (3 in bun-connect-x509.test.ts, and one each in compile-trim-features.ts, react-compiler/expected.ts, host-export-callers.test.ts, socket-dns-error.test.ts, websocket-server.test.ts). After the test edits there are 0. The five projects that the Lint workflow type-checks: 0 new.
host-export-callers.test.ts treated a signal death of git grep as "no match" (null > 1 is false). It now throws.
With a debug build and a release build of this branch: spawn-kill-signal.test.ts, spawn-maxbuf.test.ts, socket-dns-error.test.ts, websocket-server.test.ts -t remoteAddress, compile-trim-runtime.test.ts, bun-connect-x509.test.ts (the test that needs example.com fails here without network, as on main), test/aot/builtins (the same result as main) and cargo test -p bun_aot --test ir_tests lower.
Size: the two .d.ts files grow by 3203 bytes of JSDoc. Without comments, as the binary embeds them, they grow by 122 bytes, or 4 bytes after zstd (the build's own withoutComments and compression settings).
The JSDoc does not name Windows named pipes. The code gives them no address (InternalSocket::Pipe, src/uws_sys/socket.rs:698-726), but I did not run Windows.
…he socket address and TLS getters
The declarations left out the value that the runtime returns when there is
none, so a program that passed `tsc` read `null` or `undefined` as a number
or a string.
- `SyncSubprocess.exitCode` is `number | null`: `null` when a signal ended
the child.
- The six address properties of `Bun.Socket` and
`ServerWebSocket.remoteAddress` are `T | undefined`: a Unix domain socket
has no IP address, and a socket that is not connected has none to report.
- `Socket.getTLSVersion()` is `string | null`. `getServername()` and
`getPeerX509Certificate()` can return `undefined`.
- The JSDoc of each member says when the value is absent.
- The schema check no longer lists `ServerWebSocket.remoteAddress` as a
known difference.
- The docs copy of `SyncSubprocess` matches the declaration.
- Tests that read these values as always present handle the absent value.
The casts for `exitCode: null` are gone.
Status: open. CI is green on f62ef0b528 (Buildkite and the GitHub checks). The PR waits for a review.
How I reproduced it (Bun 1.4.4-canary.1+2596ac5d3 and 1.4.3, Linux x64). Each program below passes tsc --strict against the declarations of main.
// 1. A signal ends the child: exitCode is null, declared number.constr=Bun.spawnSync({cmd: [process.execPath,"-e","process.kill(process.pid, 'SIGKILL')"]});console.log(r.exitCode,r.signalCode,r.exitCode>1);// null "SIGKILL" false// 2. A Unix domain socket: all six address properties are undefined, declared string / number.Bun.listen({unix: path,socket: {open(s){console.log(s.remoteAddress,s.remotePort,s.localAddress);},data(){}}});awaitBun.connect({unix: path,socket: {data(){}}});// undefined undefined undefined// 3. A TCP WebSocket, first read in close: undefined, declared string.Bun.serve({port: 0,fetch: (req,server)=>(server.upgrade(req) ? undefined : newResponse("no")),websocket: {message(){},close(ws){ws.remoteAddress.toUpperCase();}},// TypeError: undefined is not an object});
Type proof:bun test test/integration/bun-types/bun-types.test.ts gives 30 pass on this branch. With bun.d.ts and serve.d.ts of main, the new fixture lines give 12 TS2344 diagnostics.
No actionable comments were generated in the recent review.
Walkthrough
Public socket and subprocess declarations now represent values that may be absent. Documentation, type fixtures, and related tests were updated to reflect the nullable or optional types and their documented cases.
Changes
Socket Endpoint and TLS Types
Layer / File(s)
Summary
Socket endpoint and TLS contracts with type checks packages/bun-types/bun.d.ts, packages/bun-types/serve.d.ts, test/integration/bun-types/*, test/js/bun/http/bun-connect-x509.test.ts, test/js/bun/net/socket-dns-error.test.ts, test/js/bun/websocket/websocket-server.test.ts
Socket endpoint properties, TLS accessors, peer certificates, and ServerWebSocket.remoteAddress now allow absent values in their types. The documentation describes the cases for absent values. Type fixtures and related tests check these types and cases.
SyncSubprocess.exitCode now permits null, and its documentation describes signal termination. Related fixtures and helpers account for nullable exit codes. Spawn tests assert nullable results without casts; the gitGrep check now treats null as an error result.
oven-sh/bun#46820: Both PRs address the spawnSync termination result contract, including max-buffer termination.
oven-sh/bun#46789: Both PRs concern type comparison for nullable and optional values, including ServerWebSocket.remoteAddress.
Merge Risk: Minimal · up to f62ef
The nullable declarations and dependent checks are mergeable after normal checks; neither investigated concern establishes a new failure from this change.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title clearly summarizes the main change: updating Bun type declarations for values that may be absent at runtime.
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Description check
The description explains the problem, the changes, and how the author verified them. It does not use the template’s exact headings, but it provides the required information and substantial verificatio…
Full details: Description check
Explanation
The description explains the problem, the changes, and how the author verified them. It does not use the template’s exact headings, but it provides the required information and substantial verification details.
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Bun.spawnSync().exitCodeisnullafter a signal kills the child, butbun.d.ts:8700saysnumber, soexitCode > 1is silentlyfalse.Bun.Socket(bun.d.ts:7264-7294),ServerWebSocket.remoteAddress(serve.d.ts:273) and three TLS getters have the same gap.ws.remoteAddress.toUpperCase()inclosepassestscand throwsTypeError: undefined is not an object.test/#44614 lists theexitCodegap. WebSocket: real closing handshake, one failure path,wsrewritten on native transports (consolidates the open WebSocket PRs) #45223 keepsws.remoteAddressundefinedinclose.Fix
exitCode: number | null,| undefinedfor the seven address properties,getServername()andgetPeerX509Certificate(), andgetTLSVersion(): string | null. The JSDoc says when each value is absent.node:child_processandnode:netalready read these values.test/integration/bun-types/bun-types.test.ts. The new fixture lines give 12 diagnostics onmain.Background
wsrewritten on native transports (consolidates the open WebSocket PRs) #45223 declined onegetpeernameper connection.Downsides
@types/bunget a strictNullChecks error where they read these values without a check: 8 places intest/here. Three took a signal death for a number.Bun.SocketandBun.udpSocketkeep the same gap.Notes
Runtime values, on 1.4.4-canary.1+2596ac5d3 (Linux x64) and on 1.4.3
Bun.spawnSync(...).exitCodeafter SIGKILL, and aftertimeoutormaxBufferwhen the signal ends the childnullBun.listen({ unix })orBun.connect({ unix })undefinedclose, afterclose, or inconnectErrorundefinedremoteFamily,remoteAddress,remotePortinopen, when the peer wrote and reset before the acceptundefinedremotePorton a TCP socket afterclose, also when it was read inopenundefinedws.remoteAddressoverBun.serve({ unix }), and on a TCP server when the first read is incloseundefinedgetTLSVersion()on a socket without TLS, and after a TLS socket closesnullgetServername()on a socket without TLS, after close, and when the client sent no server nameundefinedgetPeerX509Certificate()on a TLS server socket whose client sent no certificate, and after closeundefinedA child that handles the signal of
timeoutcan still exit with a code:sh -c "trap 'exit 0' TERM; sleep 5 & wait"withtimeout: 200givesexitCode: 0andexitedDueToTimeout: true. So the JSDoc ofexitCodenames the signal, not the option, as the cause.Why the declaration is the side that changes
exitCode:src/runtime/api/bun/subprocess.rs:1310returnsnullunless the child exited.spawnsync-no-microtask-drain.test.ts:87andspawn-kill-signal.test.tspinnull.src/js/node/child_process.ts:588maps it to Node'sstatus: null. The table of built-ins already saysexitCode: b.f64.nullable(src/codegen/builtins/host/globals.builtins.ts:1129).string | undefinedandu16.optional(src/runtime/socket/socket_body.bind.ts:10,:69-78).src/js/node/net.ts:3137-3165depends onundefinedfor a Unix domain socket, as Node does.socket.test.ts:5135pinsundefined.ServerWebSocket.remoteAddress:src/runtime/server/server.bind.ts:159saysstring | undefined.websocket-server.test.ts:3768pins that a value read inopenis still there inclose. The schema check inbun-types.test.tslisted this row as a known difference. The row is gone.@types/nodedeclares the Node equivalents the same way:SpawnSyncReturns.status: number | null,remoteAddress: string | undefined,localAddress?: string.Members with the same gap that this PR does not change
Checked on the same canary build.
Socket#getPeerCertificate()PeerCertificatenullwithout TLS.undefinedon a TLS server whose client sent no certificate, and after closeSocket#getCertificate()PeerCertificate | object | nullundefinedwithout TLS, on a TLS client without a certificate, and after closeSocket#getCipher()CipherNameAndProtocolundefinedwithout TLS and after closeSocket#getSharedSigalgs()string[]undefinedwithout TLS,nullafter closeSocket#exportKeyingMaterial()Bufferand asvoidundefinedwithout TLS and after closeSocket#upgradeTLS()[raw, tls]undefinedon a socket that has TLS alreadyudp.Socket#port,#address,udp.ConnectedSocket#remoteAddressnumber,SocketAddress,SocketAddressundefinedwhen the first read is afterclose()exportKeyingMaterial()needs its two declarations merged first. The UDP values are absent only after the program itself calledclose().test/#44614 have open PRs:SyncSubprocess.stdout/stderr(bun-types: type Subprocess stdio properties by what the runtime exposes for each stdio option #39283) andBun.YAML.stringify(types: fix YAML.stringify return type #34162, Implement the replacer argument of YAML, TOML and JSON5 stringify #39925).RedisClient#onconnectand#onclosereadundefinedwhen unset and are declared| null. That one is a runtime question: redis: readnullfrom an unsetonconnect/onclose, and keep only a function #48431.src/js/private.d.ts:449repeatsreadonly remoteAddress: stringfor the built-in modules, andsrc/js/node/child_process.ts:588still retypesexitCode,stdoutandstderr. Both are internal annotations and still type-check. This PR has no file undersrc/.The schema check
socket_body.bind.tsmaps tonull, so it never comparedTCPSocketandTLSSocketwithBun.Socket.robobun/e8bf2afd/schema-check-instance-classes(03be80c). It changescompare(), which bindgen: deleteb.anyand.variadic#46789 also changes, and its expected rows print type names of@types/node, which the fixture installs atlatest. It is not in this PR.Checks run
bun test test/integration/bun-types/bun-types.test.ts: 30 pass. With the two.d.tsfiles ofmain: the fixture case fails with 12 TS2344 diagnostics (spawn.ts:192-193,tcp.ts:177-185,websocket.ts:357) and the schema check prints theServerWebSocketrow.tsc --noEmitintest/: the declarations give 8 new diagnostics (3 inbun-connect-x509.test.ts, and one each incompile-trim-features.ts,react-compiler/expected.ts,host-export-callers.test.ts,socket-dns-error.test.ts,websocket-server.test.ts). After the test edits there are 0. The five projects that the Lint workflow type-checks: 0 new.host-export-callers.test.tstreated a signal death ofgit grepas "no match" (null > 1isfalse). It now throws.spawn-kill-signal.test.ts,spawn-maxbuf.test.ts,socket-dns-error.test.ts,websocket-server.test.ts -t remoteAddress,compile-trim-runtime.test.ts,bun-connect-x509.test.ts(the test that needsexample.comfails here without network, as onmain),test/aot/builtins(the same result asmain) andcargo test -p bun_aot --test ir_tests lower..d.tsfiles grow by 3203 bytes of JSDoc. Without comments, as the binary embeds them, they grow by 122 bytes, or 4 bytes after zstd (the build's ownwithoutCommentsand compression settings).InternalSocket::Pipe,src/uws_sys/socket.rs:698-726), but I did not run Windows.